home *** CD-ROM | disk | FTP | other *** search
/ Ian & Stuart's Australian Mac 1 / Ian and Stuart's One (Australia).iso / Awards / MacUser Shareware Awards 94 / System Enhancements / 1. KeyQuencer 1.2 / Developer’s toolkit / Extension code / Extension.h < prev   
Text File  |  1994-07-31  |  13KB  |  264 lines
  1. // =============================================================================
  2. // KEYQUENCER EXTENSIONS HEADER - VERSION 1.2 - AUGUST 1994
  3. // ©1994 Alessandro Levi Montalcini <lmontalcini@pmn.it>
  4. // Don’t forget to send me any cool extensions you create!
  5. // This text looks best in monaco 9 font, 4 spaces per tab, no wrapping
  6.  
  7. #ifndef _H_extension
  8. #define _H_extension
  9.  
  10. #ifndef __APPLEEVENTS__
  11. #include <AppleEvents.h>
  12. #endif
  13.  
  14. #if defined(powerc) || defined (__powerc)
  15. #pragma options align=mac68k
  16. #endif
  17.  
  18. // =============================================================================
  19. // FORMAT OF THE MAIN ROUTINE FOR A KEYQUENCER EXTENSION:
  20. // (the procedure pointer type is defined below after the record declarations)
  21.  
  22. // pascal short main(long message, ParamsPtr params, MachineHandle mac, GluePtr glue);
  23.  
  24. // =============================================================================
  25. // CONSTANTS AND RESOURCE TYPES:
  26.  
  27. #define kExtensionResType 'KQex'    //  the extension res name (not file name)
  28.                                     //  is used by the macro interpreter
  29. #define kExtensionFileType 'KQex'    //  extension file type
  30. #define kExtensionCreator 'KQue'    //  extension file creator (standard icon)
  31. #define kMaxExtParams 32            //  max # of parameters passed to an extension
  32. #define kMaxScreens 3                //  max # of screens in the MachineRec record
  33.  
  34. // =============================================================================
  35. // MESSAGES (sent to the extension):
  36.  
  37. enum {
  38.     kExtMessageInit    = 'INIT',        //  setup extension, load resources;
  39.                                     //  no ParamsPtr available here
  40.     kExtMessageRun    = 'RUN '        //  run extension; the extension resource file
  41.                                     //  is already closed
  42. };
  43.  
  44. // WARNING: GLUE WAS NOT AVAILABLE AT INITIALIZE TIME IN KEYQUENCER 1.0 (now it is)
  45. // Check for nil glue before using glue routines in your kExtMessageInit handler
  46.  
  47. // =============================================================================
  48. // RESULT CODES (returned by the extension):
  49.  
  50. enum {
  51.     kExtNoError = 0,                //  no error
  52.     kExtCallMeAgain,                //  keep calling the extension over and over
  53.     kExtCallMeAgainLater,            //  call the extension again after all other
  54.                                     //  queued commands have executed
  55.     kExtGenericError = 256,            //  positive results >= 256 stop macro execution
  56.     kExtBadEnvironment,                //  without informing the user (you may use
  57.     kExtBadParameters,                //  DisplayMessage or DisplayError to do so)
  58.     kExtTooManyParams,
  59.     kExtNotEnoughParams,
  60.     kExtUnknownKeyword,
  61.     kExtWrongApplication,
  62.     kExtNotEnoughMemory,
  63.     kExtObsoleteKeyQuencer,
  64.     kExtRequiresAppleEvents,
  65.     
  66.     kTellGenericError = -256,        //  negative results stop macro execution
  67.     kTellBadEnvironment,            //  and show a standard error message
  68.     kTellBadParameters,
  69.     kTellTooManyParams,
  70.     kTellNotEnoughParams,
  71.     kTellUnknownKeyword,
  72.     kTellWrongApplication,
  73.     kTellNotEnoughMemory,
  74.     kTellObsoleteKeyQuencer,
  75.     kTellRequiresAppleEvents
  76. };
  77.  
  78. // =============================================================================
  79. // CURRENT RECORD VERSIONS (will increase as I append more items to the records):
  80.  
  81. enum {
  82.     kCurParamsRecVers    = 1,
  83.     kCurMachineRecVers    = 1,
  84.     kCurGlueRecVers        = 3,        //  version 1 had 13 callbacks, v. 2 had 19
  85.     kCurRoutineCount    = 27        //  number of callback routines in the glue
  86. };
  87.  
  88. // =============================================================================
  89. // RECORD DEFINITIONS:
  90. // The current record contents will not be modified in future versions
  91. // although more items may be appended at the bottom of each record
  92.  
  93. typedef struct ParamsRec {
  94.     short        paramsRecVers;                //  kCurParamsRecVers
  95.     short        paramsCount;                //  number of parameters passed
  96.     long        countCalls;                    //  this field is initially set to 0,
  97.                                             //  incremented at each kExtCallMeAgain,
  98.                                             //  always 1 after kExtCallMeAgainLater
  99.     long        firstCallTicks;                //  TickCount() of first time called
  100.                                             //  (reset when result != kExtCallMeAgain)
  101.     short        extensionKey;                //  keyCode<<8 + charCode (low word of
  102.                                             //  event.message of key down event)
  103.     short        extensionModifiers;            //  event.modifiers of the key down event
  104.                                             //  that invoked the macro
  105.     long        reserved;                    //  don't touch this!
  106.     StringPtr    parameter[kMaxExtParams];    //  parameters are passed as read-only
  107.                                             //  pascal strings (including quotes if any);
  108.                                             //  all parameter processing is done by
  109.                                             //  the extension itself
  110. } ParamsRec, *ParamsPtr;
  111.  
  112. typedef struct MachineRec {
  113.     short        machineRecVers;                //  kCurMachineRecVers
  114.     short        systemVersion;                //  system version in BCD format
  115.     short        screenCount;                //  # of screens connected to this machine
  116.     short        mainScreen;                    //  index of main screen in screenBounds array
  117.     Rect        screenBounds[kMaxScreens];    //  bounds of all available screens
  118.                                             //  (call UpdateMachineRec to validate bounds)
  119.     Boolean        hasGestalt;                    //  01
  120.     Boolean        hasWaitNextEvent;            //  02
  121.     Boolean        hasAppleEvents;                //  03
  122.     Boolean        has68020;                    //  04
  123.     Boolean        hasFPU;                        //  05
  124.     Boolean        hasColorQD;                    //  06  all these flags are automatically
  125.     Boolean        has32BitQD;                    //  07  set up by KeyQuencer so the extensions
  126.     Boolean        hasFSSpec;                    //  08  don't have to call Gestalt all the time
  127.     Boolean        hasNewStdFile;                //  09
  128.     Boolean        hasNotification;            //  10
  129.     Boolean        hasAliases;                    //  11
  130.     Boolean        hasFindFolder;                //  12
  131.     Boolean        hasPartialRes;                //  13
  132.     Boolean        hasSoundManager;            //  14
  133. } MachineRec, *MachinePtr, **MachineHandle;
  134.  
  135. typedef struct GlueRec {
  136.     short                glueRecVers;            // check before using recent callbacks
  137.     short                routineCount;            // don't check this
  138.     pascal void            (*DisplayMessage)        (ConstStr255Param message, Boolean playBeep);
  139.     pascal void            (*DisplayError)            (OSErr error);
  140.     pascal void            (*StopSequence)            (void);
  141.     pascal void            (*TypeString)            (ConstStr255Param string);
  142.     pascal void            (*TypeText)                (const unsigned char *text, short length);
  143.     pascal Boolean        (*SafePostEvent)        (const EventRecord *event);
  144.     pascal void            (*WaitTicks)            (long pause);
  145.     pascal short        (*ExecuteScript)        (Handle text);
  146.     pascal Boolean        (*ExtensionAvailable)    (ConstStr255Param name);
  147.     pascal void            (*GetCharacterInfo)        (unsigned char c, short *message, short *modifiers);
  148.     pascal Boolean        (*TrapAvailable)        (short trap);
  149.     pascal void            (*ShowStartupIcon)        (short iconID);
  150.     pascal void            (*AnonymousMessage)        (ConstStr255Param message, Boolean playBeep);
  151.     
  152. // the following routines are only available in glue version 2 or later (KQ 1.1 or later);
  153. // make sure that glue->glueRecVers >= 2 before using them:
  154.     
  155.     pascal Boolean        (*AppleEventsAvail)        (void);
  156.     pascal Boolean        (*SendAppleEvent)        (const AppleEvent *event, OSErr *errPtr, Boolean bringToFront);
  157.     pascal Boolean        (*WindowsAvailable)        (void);
  158.     pascal Boolean        (*MacroRunning)            (void);
  159.     pascal Boolean        (*EqualStringPartial)    (ConstStr255Param strToFind, ConstStr255Param strToSearch, Boolean caseSens, Boolean partialMatch);
  160.     pascal long            (*SearchString)            (ConstStr255Param strToFind, const unsigned char *buffer, long size, Boolean caseSens);
  161.  
  162. // the following routines are only available in glue version 3 or later (KQ 1.2 or later);
  163. // make sure that glue->glueRecVers >= 3 before using them:
  164.     
  165.     pascal WindowPtr    (*RealFrontWindow)        (Boolean *isModalDialog);
  166.     pascal WindowPtr    (*RealNextWindow)        (WindowPtr baseWindow, Boolean *isModalDialog);
  167.     pascal Boolean        (*RealWindow)            (WindowPtr window, Boolean *isModalDialog);
  168.     pascal OSErr        (*FindKQExtFolder)        (short *vRefNum, long *dirID);
  169.     pascal short        (*OpenExtResFile)        (void);
  170.     pascal void            (*UpdateMachineRec)        (void);
  171.     pascal Boolean        (*AskQuestion)            (ConstStr255Param question, ConstStr255Param okButtonTitle, ConstStr255Param cancelButtonTitle, short defaultButton, short numTextLines);
  172.     pascal Boolean        (*AskString)            (ConstStr255Param question, StringPtr answer, ConstStr255Param okButtonTitle, ConstStr255Param cancelButtonTitle, short defaultButton, short numInputLines);
  173.  
  174. } GlueRec, *GluePtr;
  175.  
  176. // =============================================================================
  177. // GLUE - QUICK REFERENCE:
  178. /*
  179. DisplayMessage:        displays a message (pascal string) via the notification mgr,
  180.                     optionally plays a system beep
  181. DisplayError:        displays an error (common OSErr's are shown by name in KQ 1.2)
  182. StopSequence:        stops all macros and flushes the queue (same as cmd-shift-return)
  183. TypeString:            types a pascal string as if the user was typing it from the keyboard
  184. TypeText:            same as TypeString, takes a buffer instead of a pascal string
  185. SafePostEvent:        checks the event queue and posts an event if it isn't already full
  186.                     (use this instead of PPostEvent); returns true if everything OK
  187. WaitTicks:            pauses macro execution for some time after the extension has returned
  188. ExecuteScript:        executes a macro (the macro text is passed in a handle);
  189.                     returns 0 if the macro was successfully queued,
  190.                     nonzero if an error was found (this is an internal error code)
  191. ExtensionAvailable:    checks if an extension was loaded at startup
  192. GetCharacterInfo:    returns the keyCode, charCode and modifiers needed to type
  193.                     a given character with a keyDown event
  194. TrapAvailable:        checks if a trap is available (returns true if it is, false otherwise)
  195. ShowStartupIcon:    displays a startup icon (this only works at startup time,
  196.                     when the init message is received by the extension)
  197. AnonymousMessage:    displays a message (pascal string) without the extension name
  198.  
  199. // the following routines are only available in glue version 2 or later (KQ 1.1 or later);
  200. // make sure that glue->glueRecVers >= 2 before using them:
  201.  
  202. AppleEventsAvail:    returns true if KQ Apple Events is running, false otherwise;
  203.                     SendAppleEvent can do without KQ Apple Events under KQ 1.2 or later
  204. SendAppleEvent:        sends an Apple Event; the AppleEvent record is duplicated so it can
  205.                     be allocated on the stack, while the event data handle must be in
  206.                     the system zone and is disposed of automatically by SendAppleEvent;
  207.                     never call AEDisposeDesc on the AppleEvent after passing it to
  208.                     SendAppleEvent, since it's already called by KeyQuencer for you;
  209.                     *errPtr is set to 1 right away, and receives the error code when
  210.                     the event is later sent (pass nil if you don't care, but don't wait
  211.                     for this value to change inside a loop because KQ Apple Events will
  212.                     wait and send the event when it gets some CPU time at WaitNextEvent);
  213.                     if bringToFront is true, the receiving application is switched to
  214.                     the foreground before the event is sent; SendAppleEvent returns
  215.                     true if the event was successfully queued (not sent), false otherwise
  216. WindowsAvailable:    returns true if QuickDraw and the Window Manager have been initialized
  217. MacroRunning:        returns true if KeyQuencer has more extensions to call or keystrokes
  218.                     to type inside its internal queues
  219. EqualStringPartial:    compares two strings with optional case sensitivity and partial
  220.                     matching (strToFind is a subset of strToSearch); returns true if equal
  221. SearchString:        searches a string inside a buffer with optional case sensitivity;
  222.                     returns the offset of the first matching character, or a negative
  223.                     number if no match was found
  224.  
  225. // the following routines are only available in glue version 3 or later (KQ 1.2 or later);
  226. // make sure that glue->glueRecVers >= 3 before using them:
  227.  
  228. RealFrontWindow:    returns the frontmost "real" window (uses RealWindow to filter
  229.                     out weird windows and floating palettes)
  230. RealNextWindow:        returns the next "real" window behind a given base window
  231. RealWindow:            returns false for floating palettes, the desktop and other weird
  232.                     windows (this is an educated guess, not 100% reliable)
  233. FindKQExtFolder:    finds the volume reference number and directory ID of the
  234.                     "KeyQuencer Extensions" folder
  235. OpenExtResFile:        opens the extension resource file; please don't use this if you can
  236.                     do without, since PowerBook users hate to have the HD spin up
  237.                     (the opened file is NOT guaranteed to be the same file that was
  238.                     loaded at startup: it may be an updated version, or another file
  239.                     with the same name that was copied into the "KeyQuencer Extensions"
  240.                     folder); returns refnum of resfile, or -1 if the file can't be opened
  241. UpdateMachineRec:    updates the machine record (the screen information fields may change
  242.                     after startup with the new Multiple Scan monitors)
  243. AskQuestion:        displays an ok/cancel dialog and returns true if the "ok" button was
  244.                     pressed; returns false when the user cancels and when an error occurs;
  245.                     pass nil or an empty string to get the default button titles
  246. AskString:            displays a dialog with an editable text whose contents are copied
  247.                     from and passed back to the "answer" parameter; returns the same
  248.                     values you get from AskQuestion
  249. */
  250. // =============================================================================
  251. // EXTENSION PROCEDURE POINTER TYPE DEFINITION:
  252.  
  253. typedef pascal short (*ExtProcPtr)(long message, ParamsPtr params, MachineHandle mac, GluePtr glue);
  254.  
  255. // =============================================================================
  256.  
  257. #if defined(powerc) || defined(__powerc)
  258. #pragma options align=reset
  259. #endif
  260.  
  261. #endif    // _H_extension
  262.  
  263. // =============================================================================
  264.